computer: Detach codemode execs from whoever started them, and hear how they exit - #322

Codemode execs can already wait for a person: a host module calls ctx.interrupt(), the exec pauses durably, and someone answers with runtime.respond(), even after a deploy. But whoever started the exec still had to wait on it for the result. The exec tool returns only when its exec ends, so an agent that starts a refund needing approval is stuck inside its tool call until a manager answers. It can't tell the customer what's happening, and if the turn is aborted, the exec is killed with it.

This lets an exec detach: the caller stops waiting on it, the exec keeps going, and when it exits its backend hands the outcome to a function you give it. The exec tool can detach on its own once its exec waits for an answer.

Usage

There are two halves. The backend says where detached execs report back, with onDetachedExit next to its existing onWait. Detaching is a capability of the backend: only CodemodeBackend has it, and only when it has somewhere to send exits. The backend is built when the Durable Object starts, so the hook is there to receive an exit even straight after a deploy. Whoever starts an exec decides whether to detach it.

const workspace = new Workspace({
  storage: ctx.storage,
  backends: [
    new CodemodeBackend({
      loader: env.LOADER,
      onInterrupt: "replay",
      onWait: (call) => notifyManager(call), // existing: a call started waiting
      onDetachedExit: async (exec) => {
        // exec: { id, backend, status, exitCode, result?, metadata, stdout, stderr, exitedAt }
        await inbox.save(exec);
      },
    }),
  ],
});

// From an agent: detach a tool call once its exec waits for an answer...
createExecTool({ workspace, detach: true });
// ...or also once it has run for 45 seconds.
createExecTool({ workspace, detach: { afterMs: 45_000 } });

// From your own code: detach one exec.
const exec = await workspace.runtime.exec(source);
if (!(await workspace.runtime.detachExec(exec.id))) {
  // It had already exited: read its result as usual.
}

detach works the same through createAITools, the TanStack and pi tool sets, and defineExec. Without it, the tool behaves as before.

What the model sees

A tool call whose exec detaches returns straight away:

{
  "command": "export default async function () { … }",
  "cwd": null,
  "backend": "codemode",
  "executionId": "ex_123",
  "status": "waiting",
  "stdout": "Found order ORD-1042\n",
  "stderr": "",
  "waiting": [{ "callId": "ex_123:2", "payload": { "kind": "refund", "amountCents": 12900 } }],
  "note": "The run is still going. It is waiting for an answer to the calls in `waiting`, and carries on by itself once they are answered. Don't run it again: you'll get a message with its outcome when it ends."
}

The tool description says the same up front, so the model tells the user what's happening instead of running the code again. Aborting the turn after that no longer kills the exec. An exec that ends before it detaches returns its result exactly as before.

The loop

sequenceDiagram
  participant Model
  participant exec as exec tool
  participant Exec
  participant Backend
  participant App
  Model->>exec: issue refund
  exec->>Exec: start
  Exec-->>exec: waits in ctx.interrupt()
  exec->>Backend: detachExec(id)
  exec-->>Model: { executionId, status: "waiting" }
  Note over Model: tells the customer, turn ends
  App->>Exec: respond(approved)
  Exec-->>Backend: exits
  Backend-->>App: onDetachedExit(exec)
  App->>Model: new turn with the outcome

The app's part is small: save what onDetachedExit hands you, and turn it into a message for the agent. If the Durable Object might be evicted, call runtime.recover() from an alarm while execs are waiting. That resumes them after a deploy and delivers any exit onDetachedExit missed. Replay already needs this for ctx.interrupt().

Guarantees

• Every exec's outcome goes to exactly one place. detachExec() checks that the exec is still running and marks it in one transaction, and returns false if it has already exited. So an outcome reaches whoever reads the result or onDetachedExit, never both and never neither. The tool handles the edge case too: if the exec exits while a detach is going through, the tool waits to learn whether the detach took and replies to match.
• onDetachedExit doesn't lose exits. The exit is saved in the same transaction that records it, and deleted once onDetachedExit returns. If onDetachedExit throws, or the object restarts first, it's called again when the backend next connects or from runtime.recover(). Delivery is at least once, so key on exec.id.
• Execs that never detach cost nothing extra.

Other changes

• Every codemode exec's metadata is now saved with the exec. It used to be saved only for execs that could resume, so an onInterrupt: "fail" exec that a restart cut off would have reported empty metadata.
• runtime.backends() reports detachable for each backend.
• runtime.recover() now delivers missed exits for CodemodeBackend. It used to have nothing to do for this backend.

Limits

• CodemodeBackend is the only backend that can detach for now, and only with onDetachedExit. A tool with detach leaves execs on other backends attached. Building a tool with detach fails at build time if no backend can detach. runtime.detachExec() throws for an exec on a backend that can't.
• Everything here is experimental, like ctx.interrupt().

For reviewers

• To learn that its exec is waiting, the tool polls runtime.pending() every 250 milliseconds while it streams output, and stops as soon as the exec ends or detaches. A wait event on the exec's stream would avoid polling, but it would change the public WorkspaceRuntimeEvent union, which a lot of code switches on.
• The saved exit carries the result itself. Exited execs are pruned after an hour, so a later getExec() can't be relied on.
• The two commits split the backend and runtime part, onDetachedExit and detachExec(), from the tool part, exec: { detach }.
• A detached reply is a new shape in the public ExecToolOutput type, with no exitCode. Code that narrows it with "error" in output and then reads exitCode stops typechecking, as examples/rlm did; that commit fixes it. Reusing the result shape with exitCode: null would avoid that, but a detached reply would then look like a "still running" update to code that checks exitCode === null, such as the TanStack tools.

Trying it

The script-runner test "lets the exec tool detach from a run once it waits, and hears how it ended later" runs the whole loop against a real Workspace:

npm run build --workspace @cloudflare/dofs --workspace @cloudflare/computer-rpc
cd packages/computer
npx vitest run --config vitest.config.script-runner.ts -t "detach|exit"

A follow-up pull request adds examples/detached-approvals: two support agents side by side, one attached and one detached, both needing a manager to approve refunds.

Tests

• Script-runner tests check that onDetachedExit hears about:
  • an exec that completes;
  • one killed while it waits;
  • one a restart failed;
  • an exit it missed, after the hook threw or the object restarted;
  • nothing for an exec that never detached.
• A script-runner test runs the full tool loop.
• Unit tests cover:
  • detachExec() on an exec that's running, one that has exited, and on a backend without onDetachedExit;
  • each way a tool call detaches or doesn't;
  • both sides of the exit-while-detaching race;
  • aborting the turn after a detach;
  • backends that can't detach;
  • detach passing through the AI SDK and TanStack tool sets.

Docs

• docs/05_runtime_interface.md gets a "Detaching" section covering onDetachedExit and detachExec().
• docs/09_tool_interface.md gets a "Detaching" section for the tool.
• docs/17_isolate_javascript.md points to both from the section on waiting.
• The package README's status table lists both parts.

Follow-ups

• Output a codemode exec prints just before it waits only appears once the exec resumes, so a detached reply can miss the last lines. This happened before this change too.
• The note is fixed text. Apps that word things differently may want to set it.
• The shell and container backends could support detaching later.